/***********************************************************************************************************************
 * Copyright (c) 2010 Ronald D. Kurr. Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 * this file except in compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software
 * distributed under th License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 **********************************************************************************************************************/

package org.kurron.web.service;

import java.net.URL;

/**
 * This interface provides the services needed to map long URLs to shortened URLs.
 */
public interface UrlMapper
{
    /**
     * Adds a new mapping between a long URL and its shortened alias.
     * @param alias shortened alias of the original URL.
     * @param original the original, long URL.
     */
    public void addMapping( final String alias, final URL original );

    /**
     * Checks to see if a URL has already been mapped or not.
     * @param original URL to check for a mapping.
     * @return true if a mapping currently exists, false if not.
     */
    public boolean containsOriginal( final URL original );

    /**
     * Given the alias portion of the URL, this method will look up the longer, original URL.
     * @param alias key to use to look up the original URL.
     * @return the original URL.
     * @throws MappingNotFoundDeviation if the alias is not mapped to anything.
     */
    public URL toOriginal( final String alias ) throws MappingNotFoundDeviation;

    /**
     * Given a long URL, this method will return the shortened alias URL.
     * @param longUrl original URL to get the alias for.
     * @param protocol protocol to specify, typically http.
     * @param host name of the host to specify, eg. bing.com.
     * @param port port number to use, typically 80.
     * @param contextPath @return the shortened URL.
     * @return properly constructed, shorted URL.
     * @throws MappingNotFoundDeviation if the original is not mapped to an alias.
     */
    public URL toAlias( final URL longUrl,
                        final String protocol, final String host, final int port,
                        final String contextPath ) throws MappingNotFoundDeviation;
}
